
<html><head>
<title>flibs/m_vfile - flibs </title>
</head>
<! -- Generated from file 'filedir/m_vfile.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2008 Michael Baudin michael.baudin@gmail.com   -- Copyright &copy; 2008 Arjen Markus arjenmarkus@sourceforge.net
   -->
<! -- CVS: $Id: m_vfile.html,v 1.2 2008/06/16 13:45:33 relaxmike Exp $ flibs/m_vfile.n
   -->

<body>
<h1> flibs/m_vfile(n) 1.0  &quot;flibs&quot;</h1>
<h2><a name="name">NAME</a></h2>
<p>
<p> flibs/m_vfile - Processing files





<h2><a name="table_of_contents">TABLE OF CONTENTS</a></h2>
<p>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#table_of_contents">TABLE OF CONTENTS</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#synopsis">SYNOPSIS</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#description">DESCRIPTION</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview">OVERVIEW</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#portability">Portability</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#how_to_use_it">How to use it</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#error_management">Error management</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#intel_fortran_portability">Intel Fortran portability</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#rename_and_getcwd_fortran_extension">RENAME and GETCWD fortran extension</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#dynamic_or_static_buffer">Dynamic or static buffer</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#preprocessing">Preprocessing</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#example_of_compiler_settings">Example of compiler settings</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#methods">METHODS</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#static_methods">STATIC METHODS</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#copyright">COPYRIGHT</a><br>
<h2><a name="synopsis">SYNOPSIS</a></h2>
<p>
<table border=1 width=100% cellspacing=0 cellpadding=0><tr            bgcolor=lightyellow><td bgcolor=lightyellow><table 0 width=100% cellspacing=0 cellpadding=0><tr valign=top ><td ><a href="#1"><strong>vfile_rootname</strong> ( <i class='arg'>filename</i>) result ( rootname )</a></td></tr>
<tr valign=top ><td ><a href="#2"><strong>vfile_rootname</strong> ( <i class='arg'>filename</i>) result ( rootname )</a></td></tr>
<tr valign=top ><td ><a href="#3"><strong>vfile_extension</strong> ( <i class='arg'>filename</i>) result ( extension )</a></td></tr>
<tr valign=top ><td ><a href="#4"><strong>vfile_extension</strong> ( <i class='arg'>filename</i>) result ( extension )</a></td></tr>
<tr valign=top ><td ><a href="#5"><strong>vfile_tail</strong> ( <i class='arg'>filename</i>) result ( filetail )</a></td></tr>
<tr valign=top ><td ><a href="#6"><strong>vfile_tail</strong> ( <i class='arg'>filename</i>) result ( filetail )</a></td></tr>
<tr valign=top ><td ><a href="#7"><strong>vfile_dirname</strong> ( <i class='arg'>filename</i>) result ( dirname )</a></td></tr>
<tr valign=top ><td ><a href="#8"><strong>vfile_dirname</strong> ( <i class='arg'>filename</i>) result ( dirname )</a></td></tr>
<tr valign=top ><td ><a href="#9"><strong>vfile_first_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a></td></tr>
<tr valign=top ><td ><a href="#10"><strong>vfile_first_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a></td></tr>
<tr valign=top ><td ><a href="#11"><strong>vfile_last_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a></td></tr>
<tr valign=top ><td ><a href="#12"><strong>vfile_last_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a></td></tr>
<tr valign=top ><td ><a href="#13"><strong>vfile_join</strong> ( <i class='arg'>dirname</i> <i class='arg'>filename</i>) result ( fullname )</a></td></tr>
<tr valign=top ><td ><a href="#14"><strong>vfile_join</strong> ( <i class='arg'>dirname</i> <i class='arg'>, filename</i>) result ( fullname )</a></td></tr>
<tr valign=top ><td ><a href="#15"><strong>vfile_add_extension</strong> ( <i class='arg'>filename</i> <i class='arg'>, extension</i> ) result ( newname )</a></td></tr>
<tr valign=top ><td ><a href="#16"><strong>vfile_separator</strong> ( ) result ( separator )</a></td></tr>
<tr valign=top ><td ><a href="#17"><strong>vfile_pwd</strong> ( <i class='arg'>pwd</i> ?, status? )</a></td></tr>
<tr valign=top ><td ><a href="#18"><strong>vfile_exists</strong> ( <i class='arg'>filename</i> ) result ( exists )</a></td></tr>
<tr valign=top ><td ><a href="#19"><strong>vfile_exists</strong> ( <i class='arg'>filename</i> ) result ( exists )</a></td></tr>
<tr valign=top ><td ><a href="#20"><strong>vfile_rename</strong> ( <i class='arg'>filename</i> <i class='arg'>, newfn</i> ?, status? )</a></td></tr>
<tr valign=top ><td ><a href="#21"><strong>vfile_rename</strong> ( <i class='arg'>filename</i> <i class='arg'>, newfn</i> ?, status? )</a></td></tr>
<tr valign=top ><td ><a href="#22"><strong>vfile_copy</strong> ( <i class='arg'>filename</i> <i class='arg'>, targetfn</i> ?, status? ?, mode? ?, force? ?, trimline? )</a></td></tr>
<tr valign=top ><td ><a href="#23"><strong>vfile_copy</strong> ( <i class='arg'>filename</i> <i class='arg'>, targetfn</i> ?, status? ?, mode? ?, force? ?, trimline? )</a></td></tr>
<tr valign=top ><td ><a href="#24"><strong>vfile_delete</strong> ( <i class='arg'>filename</i> ?, force? ?, status? )</a></td></tr>
<tr valign=top ><td ><a href="#25"><strong>vfile_delete</strong> ( <i class='arg'>filename</i> ?, force? ?, status? )</a></td></tr>
<tr valign=top ><td ><a href="#26"><strong>vfile_isdirectory</strong> ( <i class='arg'>filename</i>) result ( isdirectory )</a></td></tr>
<tr valign=top ><td ><a href="#27"><strong>vfile_isdirectory</strong> ( <i class='arg'>filename</i>) result ( isdirectory )</a></td></tr>
<tr valign=top ><td ><a href="#28"><strong>vfile_isfile</strong> ( <i class='arg'>filename</i>) result ( isfile )</a></td></tr>
<tr valign=top ><td ><a href="#29"><strong>vfile_isfile</strong> ( <i class='arg'>filename</i>) result ( isfile )</a></td></tr>
<tr valign=top ><td ><a href="#30"><strong>vfile_size</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_size )</a></td></tr>
<tr valign=top ><td ><a href="#31"><strong>vfile_size</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_size )</a></td></tr>
<tr valign=top ><td ><a href="#32"><strong>vfile_atime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_atime )</a></td></tr>
<tr valign=top ><td ><a href="#33"><strong>vfile_atime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_atime )</a></td></tr>
<tr valign=top ><td ><a href="#34"><strong>vfile_mtime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_mtime )</a></td></tr>
<tr valign=top ><td ><a href="#35"><strong>vfile_mtime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_mtime )</a></td></tr>
<tr valign=top ><td ><a href="#36"><strong>vfile_normalize</strong> ( <i class='arg'>filename</i> ) result ( vfile_normalize )</a></td></tr>
<tr valign=top ><td ><a href="#37"><strong>vfile_normalize</strong> ( <i class='arg'>filename</i> ) result ( vfile_normalize )</a></td></tr>
<tr valign=top ><td ><a href="#38"><strong>vfile_find</strong> ( ?basedir? ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#39"><strong>vfile_find</strong> ( <i class='arg'>basedir</i> ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#40"><strong>vfile_find</strong> ( ?basedir? <i class='arg'>, filtercmd</i> ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#41"><strong>vfile_find</strong> ( <i class='arg'>basedir</i> <i class='arg'>, filtercmd</i> ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#42"><strong>vfile_findbypattern</strong> ( ?basedir? <i class='arg'>, pattern</i> ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#43"><strong>vfile_findbypattern</strong> ( ?basedir? <i class='arg'>, pattern</i> ) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#44"><strong>vfile_listfiles</strong> ( ?directory? ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#45"><strong>vfile_listfiles</strong> ( <i class='arg'>directory</i> ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )</a></td></tr>
<tr valign=top ><td ><a href="#46"><strong>vfile_type</strong> ( <i class='arg'>filename</i> ?, status?) result ( filetype )</a></td></tr>
<tr valign=top ><td ><a href="#47"><strong>vfile_type</strong> ( <i class='arg'>filename</i> ?, status?) result ( filetype )</a></td></tr>
<tr valign=top ><td ><a href="#48"><strong>vfile_split</strong> ( <i class='arg'>filename</i>) result ( listOfComponents )</a></td></tr>
<tr valign=top ><td ><a href="#49"><strong>vfile_split</strong> ( <i class='arg'>filename</i>) result ( listOfComponents )</a></td></tr>
<tr valign=top ><td ><a href="#50"><strong>vfile_touch</strong> ( <i class='arg'>filename</i> ?, status?)</a></td></tr>
<tr valign=top ><td ><a href="#51"><strong>vfile_touch</strong> ( <i class='arg'>filename</i> ?, status?)</a></td></tr>
<tr valign=top ><td ><a href="#52"><strong>vfile_pathtype</strong> ( <i class='arg'>filename</i>) result ( pathtype )</a></td></tr>
<tr valign=top ><td ><a href="#53"><strong>vfile_pathtype</strong> ( <i class='arg'>filename</i>) result ( pathtype )</a></td></tr>
<tr valign=top ><td ><a href="#54"><strong>vfile_nativename</strong> ( <i class='arg'>filename</i>) result ( nativename )</a></td></tr>
<tr valign=top ><td ><a href="#55"><strong>vfile_nativename</strong> ( <i class='arg'>filename</i>) result ( nativename )</a></td></tr>
<tr valign=top ><td ><a href="#56"><strong>vfile_mkdir</strong> ( <i class='arg'>filename</i> ?, status?)</a></td></tr>
<tr valign=top ><td ><a href="#57"><strong>vfile_mkdir</strong> ( <i class='arg'>filename</i> ?, status?)</a></td></tr>
<tr valign=top ><td ><a href="#58"><strong>vfile_open</strong> ( <i class='arg'>filename</i> ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )</a></td></tr>
<tr valign=top ><td ><a href="#59"><strong>vfile_open</strong> ( <i class='arg'>filename</i> ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )</a></td></tr>
<tr valign=top ><td ><a href="#60"><strong>vfile_startup</strong> ()</a></td></tr>
<tr valign=top ><td ><a href="#61"><strong>vfile_shutdown</strong> ()</a></td></tr>
<tr valign=top ><td ><a href="#62"><strong>vfile_set_stoponerror</strong> ( <i class='arg'>stoponerror</i> )</a></td></tr>
<tr valign=top ><td ><a href="#63"><strong>vfile_tempdir</strong> () result ( tempdir )</a></td></tr>
<tr valign=top ><td ><a href="#64"><strong>vfile_tempfile</strong> result ( tempfile )</a></td></tr>
<tr valign=top ><td ><a href="#65"><strong>vfile_volumes</strong> result ( listofvolumes )</a></td></tr>
</table></td></tr></table>
<h2><a name="description">DESCRIPTION</a></h2>
<p>

The module <em>m_vfile</em> provides OO services to process files and directories.
This component is based on a dynamic strings so that the
file or directory name may be defined with no limit in the
number of characters.

<h2><a name="overview">OVERVIEW</a></h2>
<p>

   This component allows to manage the file system, by providing 
   services to create, move and destroy files and directories, and 
   to get informations about files and directories.
   The services provided are based either on standard fortran,
   or on fortran extensions.

<h3><a name="portability">Portability</a></h3>
<p>

   One of the main interest of this component is to separate
   the client-side application from platform-specific file 
   management or from compiler-specific fortran extensions. 

<p>

   This separation is possible because m_vfile
   deals for the platform directly, by using the m_platform
   module. This allows to design a client source code which 
   portable on several operating systems (for example windows,
   linux) without any change. For example, the several file 
   separators used on the various operating systems are taken
   into account internally : &quot;/&quot; on linux systems, &quot;\&quot; on 
   windows systems and &quot;:&quot; on Mac OS.

<p>

   The portability is also ensured with respect to the 
   fortran compiler used to create the executable.
   All fortran compilers provide commands to rename the files
   or get the working directory. But not all fortran compilers
   define these commands the same way : some provide subroutines,
   some provide functions, etc... The current component can 
   be configured at compile-time with pre-processing commands.
   This allows to configure the component with compiler 
   specific settings, to make so that the component know
   what features your particular compiler knows about.

<p>

     &lt;your application&gt; &gt; m_vfile (operating system , fortran compiler) &gt; m_platform (operating system , fortran compiler)

 <h3><a name="how_to_use_it">How to use it</a></h3>
<p>

   Before using the services provided by m_vfile, the client
   code must call vfile_startup which initializes platform-specific 
   commands. After using these services, the client code should call
   vfile_shutdown.

<p>

   The commands vfile_delete, vfile_copy, vfile_rename
   allow to delete, copy and rename files or directories.
   To inquire about a file or directory, one can use 
   vfile_exists or vfile_isdirectory.
  
<p>

   In the following example, one creates a new file with vfile_touch,
   rename that file and finally delete it.

<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
     call vfile_startup ()
     call vstring_new ( file , &quot;foo.txt&quot; )
     call vfile_touch ( file )
     call vfile_rename ( file , &quot;toto.txt&quot; )
     call vfile_delete ( file )
     call vstring_free ( file )
     call vfile_shutdown ()
</pre></td></tr></table></p>

<p>

   The component makes no differences between file names 
   and directory names, except for methods which are specific 
   for file or for directory.

<p>

   The vfile_separator method returns the platform-specific character 
   used on the current operating system.

<p>

   The commands vfile_nativename , vfile_normalize , vfile_pathtype
   provide ways to manage file names and paths.
   The vfile_nativename function returns the platform-specific name of the file. 
   The vfile_pathtype command returns one of VFILE_PATHTYPE_ABSOLUTE, 
   VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE which correspond to 
   the current file. The VFILE_PATHTYPE_VOLUMERELATIVE only exist on 
   windows. The vfile_normalize command returns a unique normalized 
   path representation for the file-system object (file, directory, link, 
   etc), whose string value can be used as a unique identifier for it.

<p>

   The vfile_split and vfile_join services allows to separate
   or concatenate the components of a file. This can be useful
   when dealing with relative file or directories.
   The vfile_split command splits a file into pieces each time 
   the platform-specific separator is found.
   The vfile_join command concatenate a list of strings with 
   the platform-specific separator and returns the concatenated
   file name.

<p>

   In the following example, extracted from the unit tests included in flibs,
   the file &quot;declaration.txt&quot; is first normalized, so that the normalized 
   dynamic string may have the value
   &quot;/home/bill/flibs/tests/filedir/declaration.txt&quot; under Windows 
   or &quot;C:/workbench/flibs/tests/filedir/declaration.txt&quot; under Linux.
   Then the file name is split into a list of strings, for example &quot;home&quot;,
   &quot;bill&quot;, &quot;flibs&quot;, &quot;tests&quot;, &quot;filedir&quot;, &quot;declaration.txt&quot;.
   The number of strings in the list is then computed with the method 
   vstrlist_length.

<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
     use m_vstring
     use m_vstringlist
     use m_vfile
     type ( t_vstring ) :: normalized
     type ( t_vstringlist ) :: listOfFiles
     integer :: numberOfStrings
     normalized = vfile_normalize ( &quot;declaration.txt&quot; )
     listOfFiles = vfile_split ( normalized )
     numberOfStrings = vstrlist_length ( listOfFiles )
</pre></td></tr></table></p>

<p>

   One particularly useful command when dealing with files is 
   vfile_findbypattern. The command takes a string as an input
   file pattern. It then computes the list of all files which
   match that pattern. The string matching system is based on 
   the vstring_match method of the m_vstring module.

<p>

   In the following example, extracted again from the unit tests
   of flibs, one computes the list of files in the directory &quot;testfindbypattern&quot;
   matching the pattern &quot;*dec*.txt&quot;.

<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
     type ( t_vstringlist ) :: listOfFiles
     listOfFiles = vfile_findbypattern ( &quot;testfindbypattern&quot; , pattern = &quot;*dec*.txt&quot; )
</pre></td></tr></table></p>

 <h3><a name="error_management">Error management</a></h3>
<p>

   The file management may raise errors, for example when the 
   user want to rename a file which does not exist.
   Many of the provided commands have an optional integer output 
   argument &quot;status&quot; which is zero when no error occurred 
   and non-zero in case of error.
   If the status argument is not provided and an error is generated,
   then the program stops and a message is displayed on standard 
   output.
   These are the public error flags that the current component may generate :

<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
     VFILE_ERROR_OK
     VFILE_ERROR_UNABLE_TO_OPEN_SOURCE
     VFILE_ERROR_UNABLE_TO_OPEN_TARGET
     VFILE_ERROR_UNABLE_TO_WRITE_TARGET
     VFILE_ERROR_SOURCE_FILE_DOES_NOT_EXIST
</pre></td></tr></table></p>

<h3><a name="intel_fortran_portability">Intel Fortran portability</a></h3>
<p>

Several methods of this component are based on Fortran extensions,
which requires compiler-specific settings.
For Intel Fortran compiler, the current implementation was based on
IFPORT.F90 file in the Intel release for details on the interfaces provided.
If the client code use these routines, it must define the pre-processing
macro _VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES

<h3><a name="rename_and_getcwd_fortran_extension">RENAME and GETCWD fortran extension</a></h3>
<p>

Depending on the compiler, the &quot;RENAME&quot; fortran extension is
provided as a subroutine or a function.
For example, this is a short list of compilers and their particular
RENAME provided :
<ul>
<li> function : Intel Fortran, g95
<br><br>
<li> subroutine : gfortran
</ul>
To inform the m_vfile module of the particular RENAME extension, 
one of the following pre-processing macro must be defined :
<ul>
<li> _VFILE_RENAME_FUNCTION
<br><br>
<li> _VFILE_RENAME_SUBROUTINE
</ul>

<p>
The same situation happens with the GETCWD fortran extension. 
To inform the m_vfile module of the particular GETCWD extension, 
one of the following pre-processing macro must be defined :
<ul>
<li> _VFILE_GETCWD_FUNCTION
<br><br>
<li> _VFILE_GETCWD_SUBROUTINE
</ul>

<h3><a name="dynamic_or_static_buffer">Dynamic or static buffer</a></h3>
<p>

The internal algorithms provided by m_vstrings are based on
basic fortran character strings. In several situations, the
dynamic vstring has to be converted into a basic fortran character
buffer string, which size has to be given explicitly in the source
code, with &quot;character ( len = &lt;something&gt;)&quot; statement.
Two solutions are provided, and the user can define the pre-processing macro
_VFILE_STATIC_BUFFER to configure that :
<ul>
<li> the first solution is to set the size of the buffer statically,
to a constant integer value VSTRING_BUFFER_SIZE.
<br><br>
<li> the second solution is to compute the size
of the buffer dynamically, with the fortran 90 len = vstring_length(this)
statement.
</ul>

If the _VFILE_STATIC_BUFFER is defined, then character strings of
constant size are used as buffers.
If the _VFILE_STATIC_BUFFER is not defined (which is the default),
then character strings of dynamic size are used as buffers.
The second solution is more efficient, because the strings are not
oversized or undersized, depending on the real number of characters
in the dynamic string. But the feature may not be provided
by the compiler at hand. For example, problems with the dynamic
length character string have been experienced with Intel Fortran 8.

<h3><a name="preprocessing">Preprocessing</a></h3>
<p>
The following preprocessing macro must be considered :
<ul>
<li> _VFILE_STATIC_BUFFER : see  the section &quot;Dynamic or static buffer&quot;
<br><br>
<li> _VFILE_RENAME_FUNCTION or _VFILE_RENAME_SUBROUTINE : see the section &quot;RENAME and GETCWD fortran extension&quot;
<br><br>
<li> _VFILE_GETCWD_FUNCTION or _VFILE_GETCWD_SUBROUTINE : see the section &quot;RENAME and GETCWD fortran extension&quot;
</ul>

<h3><a name="example_of_compiler_settings">Example of compiler settings</a></h3>
<p>

This is an abstract of all macros for several compilers.

<p>

Compiler : <em>Intel Fortran V8.0</em>
<ul>
<li> _VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES
<br><br>
<li> _VFILE_RENAME_FUNCTION
<br><br>
<li> _VFILE_STATIC_BUFFER
<br><br>
<li> _VFILE_GETCWD_FUNCTION
</ul>

<p>
Compiler : <em>g95</em>
<ul>
<li> _VFILE_RENAME_FUNCTION
<br><br>
<li> _VFILE_GETCWD_FUNCTION
</ul>

<p>
Compiler : <em>gfortran</em>
<ul>
<li> _VFILE_RENAME_SUBROUTINE
<br><br>
<li> _VFILE_GETCWD_SUBROUTINE
</ul>

<h2><a name="methods">METHODS</a></h2>
<p>


<dl>


<dt><a name="1"><strong>vfile_rootname</strong> ( <i class='arg'>filename</i>) result ( rootname )</a><dd>

<dl>
<dt><strong>type ( t_vstring ) , intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>rootname</i><dd>
</dl>
Returns the name without the extension (if any), that is, 
The part of the name _before_ the last &quot;.&quot; in <i class='arg'>filename</i> or the whole name
if no &quot;.&quot; is present in <i class='arg'>filename</i>. 
Example : if filename is &quot;declaration.txt&quot;, the file root name is &quot;declaration&quot;.

<br><br>
<dt><a name="2"><strong>vfile_rootname</strong> ( <i class='arg'>filename</i>) result ( rootname )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>rootname</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="3"><strong>vfile_extension</strong> ( <i class='arg'>filename</i>) result ( extension )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>extension</i><dd>
</dl>
Returns the extension (if any), that is the part of the name 
<em>after</em> and including the last &quot;.&quot; or empty if none
present. Example : if filename is &quot;declaration.txt&quot;, the file extension is &quot;.txt&quot;.

<br><br>
<dt><a name="4"><strong>vfile_extension</strong> ( <i class='arg'>filename</i>) result ( extension )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>extension</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.

<br><br>
<dt><a name="5"><strong>vfile_tail</strong> ( <i class='arg'>filename</i>) result ( filetail )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>filetail</i><dd>
</dl>
Returns all of the characters in name after the last directory separator.
If <i class='arg'>filename</i> contains no separators then returns <i class='arg'>filename</i>.
Example : if filename is &quot;dir1/declaration.txt&quot;, the file tail is &quot;declaration.txt&quot;.


<br><br>
<dt><a name="6"><strong>vfile_tail</strong> ( <i class='arg'>filename</i>) result ( filetail )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>filetail</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="7"><strong>vfile_dirname</strong> ( <i class='arg'>filename</i>) result ( dirname )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>dirname</i><dd>
</dl>
Return the directory, that is, the part of the name <em>before</em> 
the last directory separator.
Example : if filename is &quot;dir1/declaration.txt&quot;, the directory name 
is &quot;dir1&quot;.


<br><br>
<dt><a name="8"><strong>vfile_dirname</strong> ( <i class='arg'>filename</i>) result ( dirname )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>dirname</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="9"><strong>vfile_first_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>sepindex</i><dd>
</dl>
Returns the index of the first separator in the given filename
or 0 if there is no separator in the given file name.


<br><br>
<dt><a name="10"><strong>vfile_first_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>sepindex</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="11"><strong>vfile_last_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>sepindex</i><dd>
</dl>
Returns the index of the last separator in the given filename
or 0 if there is no separator in the given file name.


<br><br>
<dt><a name="12"><strong>vfile_last_separator_index</strong> ( <i class='arg'>filename</i>) result ( sepindex )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>sepindex</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="13"><strong>vfile_join</strong> ( <i class='arg'>dirname</i> <i class='arg'>filename</i>) result ( fullname )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>dirname</i><dd>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>fullname</i><dd>
</dl>
Join the current file with the given file name,
using the platform-specific separator as the joining character.
The result is always canonical for the current platform: / for
Unix and Windows, and : for Macintosh.
If a particular name is relative, then it will be joined to the previous
file name argument. Otherwise, any earlier arguments will be discarded,
and joining will proceed from the current argument. 


<br><br>
<dt><a name="14"><strong>vfile_join</strong> ( <i class='arg'>dirname</i> <i class='arg'>, filename</i>) result ( fullname )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>dirname</i><dd>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>fullname</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="15"><strong>vfile_add_extension</strong> ( <i class='arg'>filename</i> <i class='arg'>, extension</i> ) result ( newname )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>extension</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>newname</i><dd>
</dl>
Return a new file name with the given extension concatenated.
If the given file name ends with a dot and the given extension begins
with a dot, only one dot is kept.
Note that the extension of one file begins with a dot : &quot;.txt&quot; is a file
extension while &quot;txt&quot; is not.


<br><br>
<dt><a name="16"><strong>vfile_separator</strong> ( ) result ( separator )</a><dd>

<dl>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>separator</i><dd>
</dl>
Return the native separator for the current platform
The separator depends on the platform :
<br><br>
<ul>
<li> &quot;/&quot; on Unix, Linux systems,
<br><br>
<li> &quot;\&quot; on Windows systems,
<br><br>
<li> &quot;:&quot; on Macintosh.
</ul>


<dt><a name="17"><strong>vfile_pwd</strong> ( <i class='arg'>pwd</i> ?, status? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>pwd</i><dd>
<dt><strong>integer , intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Returns the name of the current directory by using the fortran
extension GETCWD.
The separator used here is the platform-independent &quot;/&quot;.


<br><br>
<dt><a name="18"><strong>vfile_exists</strong> ( <i class='arg'>filename</i> ) result ( exists )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>exists</i><dd>
</dl>
Returns .true. if file name exists, .false. otherwise.


<br><br>
<dt><a name="19"><strong>vfile_exists</strong> ( <i class='arg'>filename</i> ) result ( exists )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>exists</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="20"><strong>vfile_rename</strong> ( <i class='arg'>filename</i> <i class='arg'>, newfn</i> ?, status? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>newfn</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Renames the file ofdln to newfn by using the RENAME fortran extension.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.



<br><br>
<dt><a name="21"><strong>vfile_rename</strong> ( <i class='arg'>filename</i> <i class='arg'>, newfn</i> ?, status? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>newfn</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Same as previous but with <i class='arg'>newfn</i> as a character string.



<br><br>
<dt><a name="22"><strong>vfile_copy</strong> ( <i class='arg'>filename</i> <i class='arg'>, targetfn</i> ?, status? ?, mode? ?, force? ?, trimline? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>targetfn</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>character(len=*), intent(in), optional ::</strong> <i class='arg'>mode</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>force</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>trimline</i><dd>
</dl>
Copy the ascii file ofdln to targetfn.
If the source file does not exists, generates an error.
If the target file allready exists and force option is undefined
or defined to false, generates an error.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return
<br><br>
<ul>
<li> status = 1 when one was unable to open the source file
<br><br>
<li> status = 2 when one was unable to open the target file
<br><br>
<li> status = 3 when there was a problem while writing the target file
<br><br>
<li> status = 4 when the source file does not exist
</ul>
If <i class='arg'>mode</i> is not supplied or supplied and equals to &quot;system&quot;, then 
the copy is made using an operating system command.
If <i class='arg'>mode</i> is supplied and equals to &quot;ascii&quot;, then the copy is made using standard
fortran.
The <i class='arg'>force</i> option is available only in &quot;ascii&quot; mode. 
If <i class='arg'>force</i> is supplied and true, if the target file allready exists, delete it before
making the copy. 
The <i class='arg'>trimline</i> option is available only in &quot;ascii&quot; mode. 
If <i class='arg'>trimline</i> is supplied and true, or not supplied, the lines of 
the file copy are trimmed.
If <i class='arg'>trimline</i> is supplied and false, the number of columns in the file copy are all
of maximum possible length.
<br><br>
The &quot;ascii&quot; mode may not behave as expected :
<br><br>
<ul>
<li> The maximum number of columns in the source filename is 1000.
<br><br>
<li> After execution, the target file is not an exact copy of the source file.
Because of the fortran format used, all the lines of the target file are of length 1000 :
blank spaces are appended at the end of the string.
</ul>



<dt><a name="23"><strong>vfile_copy</strong> ( <i class='arg'>filename</i> <i class='arg'>, targetfn</i> ?, status? ?, mode? ?, force? ?, trimline? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>targetfn</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>character(len=*), intent(in), optional ::</strong> <i class='arg'>mode</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>force</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>trimline</i><dd>
</dl>
Same as previous but with <i class='arg'>targetfn</i> as a character string.



<br><br>
<dt><a name="24"><strong>vfile_delete</strong> ( <i class='arg'>filename</i> ?, force? ?, status? )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>force</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Removes the file or directory <i class='arg'>filename</i>. 
Non-empty directories will be removed only if the <i class='arg'>force</i> option is specified.
If <i class='arg'>force</i> is supplied and true, forces to delete the directory, even if it is empty.
If <i class='arg'>force</i> is not supplied or supplied and false, the directory is not deleted if it is empty.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.



<br><br>
<dt><a name="25"><strong>vfile_delete</strong> ( <i class='arg'>filename</i> ?, force? ?, status? )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical, intent(in) , optional ::</strong> <i class='arg'>force</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="26"><strong>vfile_isdirectory</strong> ( <i class='arg'>filename</i>) result ( isdirectory )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>isdirectory</i><dd>
</dl>
Returns .true. if file name is a directory, .false. otherwise.

<br><br>
<dt><a name="27"><strong>vfile_isdirectory</strong> ( <i class='arg'>filename</i>) result ( isdirectory )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>isdirectory</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="28"><strong>vfile_isfile</strong> ( <i class='arg'>filename</i>) result ( isfile )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>isfile</i><dd>
</dl>
Returns .true. if file name is a file, .false. otherwise.

<br><br>
<dt><a name="29"><strong>vfile_isfile</strong> ( <i class='arg'>filename</i>) result ( isfile )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>logical ::</strong> <i class='arg'>isfile</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="30"><strong>vfile_size</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_size )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_size</i><dd>
</dl>
Returns .true. if file name is a file, .false. otherwise.
Returns an integer giving the size of file name in bytes. 
If the file doesn't exist or its size cannot be queried then an error is generated.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.

<br><br>
<dt><a name="31"><strong>vfile_size</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_size )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_size</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="32"><strong>vfile_atime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_atime )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_atime</i><dd>
</dl>
Returns an integer representing the time at which file name was last accessed.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.


<br><br>
<dt><a name="33"><strong>vfile_atime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_atime )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_atime</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="34"><strong>vfile_mtime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_mtime )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_mtime</i><dd>
</dl>
Returns an integer representing the time at which file name was last modified.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.


<br><br>
<dt><a name="35"><strong>vfile_mtime</strong> ( <i class='arg'>filename</i> ?, status?) result ( vfile_mtime )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>vfile_mtime</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="36"><strong>vfile_normalize</strong> ( <i class='arg'>filename</i> ) result ( vfile_normalize )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>vfile_normalize</i><dd>
</dl>
Returns a unique normalized path representation for the
file-system object (file, directory, link, etc), whose string
value can be used as a unique identifier for it. A normalized path
is an absolute path which has all '../', './' removed. Also it is one which
is in the ``standard'' format for the native platform.
On Windows or Mac, any platform-specific separator in the path
is replaced by the platform-independent separator &quot;/&quot;.
On Windows it also means we want the long form with that form's
case-dependence (which gives us a unique, case-dependent path).

<br><br>
<dt><a name="37"><strong>vfile_normalize</strong> ( <i class='arg'>filename</i> ) result ( vfile_normalize )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>vfile_normalize</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="38"><strong>vfile_find</strong> ( ?basedir? ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in), optional ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
An implementation of the unix command find.
Returns a list of files or directories which are located in the
given basedir directory, and, recursively, in all sub-directories.
Each file in the resulting list has a path relative to the given
basedir directory.
If <i class='arg'>basedir</i> is provided, this is the name of the base directory into which the search is done.
If <i class='arg'>basedir</i> is not provided, the current directory is used by default.

<br><br>
<dt><a name="39"><strong>vfile_find</strong> ( <i class='arg'>basedir</i> ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
Same as previous but with <i class='arg'>basedir</i> as a character string.


<br><br>
<dt><a name="40"><strong>vfile_find</strong> ( ?basedir? <i class='arg'>, filtercmd</i> ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in), optional ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
    interface
       function filtercmd ( filename ) result ( keepfile )
         use m_vstring, only : t_vstring
         type ( t_vstring ), intent(in) :: filename
         logical :: keepfile
       end function filtercmd
    end interface</pre></td></tr></table></p>
An implementation of the unix command find.
Returns a list of files or directories which are located in the
given basedir directory, and, recursively, in all sub-directories.
Each file in the resulting list has a path relative to the given
basedir directory.
If <i class='arg'>basedir</i> is provided, this is the name of the base directory into which the search is done.
If <i class='arg'>basedir</i> is not provided, the current directory is used by default.
The <i class='arg'>filtercmd</i> command, if provided, is interpreted as a command prefix and 
one argument is passed to it, the name of the file or directory find is currently
looking at. Note that this name is not fully qualified. It has to be joined it with
the result of pwd to get an absolute filename. The result of filtercmd is a boolean value
that indicates if the current file should be included in the list of interesting files.


<br><br>
<dt><a name="41"><strong>vfile_find</strong> ( <i class='arg'>basedir</i> <i class='arg'>, filtercmd</i> ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
    interface
       function filtercmd ( filename ) result ( keepfile )
         use m_vstring, only : t_vstring
         type ( t_vstring ), intent(in) :: filename
         logical :: keepfile
       end function filtercmd
    end interface</pre></td></tr></table></p>
Same as previous but with <i class='arg'>basedir</i> as a character string.



<br><br>
<dt><a name="42"><strong>vfile_findbypattern</strong> ( ?basedir? <i class='arg'>, pattern</i> ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in), optional ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
Returns a list of files which match the given pattern.
Internally, this command is based on vfile_find, with a particular filter command applied.
If <i class='arg'>basedir</i> is provided, this is the name of the base directory into which the search is done.
If <i class='arg'>basedir</i> is not provided, the current directory is used by default.
The <i class='arg'>pattern</i> is the pattern for the file names (like: *.f90) against which 
each file name is compared. The method used for string matching 
is vstring_match, so that all features available is vstring_match are 
available in vfile_findbypattern.


<br><br>
<dt><a name="43"><strong>vfile_findbypattern</strong> ( ?basedir? <i class='arg'>, pattern</i> ) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in), optional ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
Same as previous but with <i class='arg'>basedir</i> and <i class='arg'>pattern</i> as a character string.




<br><br>
<dt><a name="44"><strong>vfile_listfiles</strong> ( ?directory? ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in), optional ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ), intent(in), optional ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>type ( t_vstring ), intent(in), optional ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>logical, intent(in), optional ::</strong> <i class='arg'>tails</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
Returns a list of files in one directory.
Only the file tails are in the list.
If <i class='arg'>directory</i> is provided, the directory into which the list is to be computed.
If <i class='arg'>directory</i> is not provided, the current directory is used and only the file names are file tails.
If <i class='arg'>directory</i> is provided, the computed files names are relative and begin with the given 
directory (following the template directory/filetail).
If <i class='arg'>filetypes</i> is provided, only list files or directories which match filetypes,
with d (directory), f (plain file).
If <i class='arg'>filetypes</i> is not provided, the filetypes &quot;d&quot; , &quot;f&quot; list is used.
If <i class='arg'>pattern</i> is provided, only list files which match the given pattern.
If <i class='arg'>pattern</i> is not provided, the &quot;*&quot; pattern is used.
The vstring_match command is used to compare the file against the pattern so that
all the pattern types available in vstring_match are available in vfile_listfiles.
If <i class='arg'>tails</i> is provided and true, only return the part of each file found 
which follows the last directory named in directory.
Thus the statement
<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
listoffiles = vfile_listfile ( tails = .true. , directory = directory , pattern = &quot;*&quot; )
</pre></td></tr></table></p>
is equivalent to
<p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
call vfile_pwd ( cwd )
call vstrplatform_cd ( directory )
listoffiles = vfile_listfile ( tails = .true. , pattern = &quot;*&quot; )
call vstrplatform_cd ( cwd )
</pre></td></tr></table></p>
If <i class='arg'>tails</i> is provided and false, or not provided, the files are left as specified by the
directory argument.

<br><br>
<dt><a name="45"><strong>vfile_listfiles</strong> ( <i class='arg'>directory</i> ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>basedir</i><dd>
<dt><strong>type ( t_vstringlist ), intent(in), optional ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>character(len=*), intent(in), optional ::</strong> <i class='arg'>pattern</i><dd>
<dt><strong>logical, intent(in), optional ::</strong> <i class='arg'>tails</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfFiles</i><dd>
</dl>
Same as previous but with <i class='arg'>directory</i> and <i class='arg'>pattern</i> as a character string.



<br><br>
<dt><a name="46"><strong>vfile_type</strong> ( <i class='arg'>filename</i> ?, status?) result ( filetype )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer , intent(out), optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>filetype</i><dd>
</dl>
Returns a string giving the type of file name, which will be one of &quot;file&quot; or &quot;directory&quot;.
If <i class='arg'>status</i> is provided and the file type could be computed,
the status is set to 0.
If <i class='arg'>status</i> is provided and the file type could not be computed,
the status is set to VFILE_ERROR_UNKNOWN_FILE_TYPE.
If <i class='arg'>status</i> is not provided and the file type could not be computed,
an error is generated.



<br><br>
<dt><a name="47"><strong>vfile_type</strong> ( <i class='arg'>filename</i> ?, status?) result ( filetype )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer , intent(out), optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>filetype</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.




<br><br>
<dt><a name="48"><strong>vfile_split</strong> ( <i class='arg'>filename</i>) result ( listOfComponents )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfComponents</i><dd>
</dl>
Returns a list of strings where elements are the path components in name.


<br><br>
<dt><a name="49"><strong>vfile_split</strong> ( <i class='arg'>filename</i>) result ( listOfComponents )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listOfComponents</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="50"><strong>vfile_touch</strong> ( <i class='arg'>filename</i> ?, status?)</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Implementation of touch. Alter the atime and mtime of the specified files. 
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.
If <i class='arg'>status</i> is not provided and the process could not be done,
an error is generated.


<br><br>
<dt><a name="51"><strong>vfile_touch</strong> ( <i class='arg'>filename</i> ?, status?)</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="52"><strong>vfile_pathtype</strong> ( <i class='arg'>filename</i>) result ( pathtype )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>pathtype</i><dd>
</dl>
Returns one of VFILE_PATHTYPE_ABSOLUTE, VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE. 
If <i class='arg'>filename</i> refers to a specific file on a specific volume, the path
type will be absolute. If <i class='arg'>filename</i> refers to a file relative to the current
working directory, then the path type will be relative. If name refers to
a file relative to the current working directory on a specified volume, or to
a specific file on the current working volume, then the path type is volumerelative.
<br><br>
Examples :
<br><br>
<ul>
<li> &quot;.&quot; is relative on all platforms
<br><br>
<li> &quot;..&quot; is relative on all platforms
<br><br>
<li> &quot;/&quot; is absolute on Linux/Unix
<br><br>
<li> &quot;C:/&quot; is absolute on Windows (if the C:/ exists)
<br><br>
<li> &quot;/&quot; is volumerelative on windows and refers to the current volume (for example C:/)
<br><br>
<li> &quot;toto.txt&quot; is relative on all platforms
<br><br>
<li> &quot;./toto.txt&quot; is relative on all platforms
</ul>


<dt><a name="53"><strong>vfile_pathtype</strong> ( <i class='arg'>filename</i>) result ( pathtype )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>pathtype</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.



<br><br>
<dt><a name="54"><strong>vfile_nativename</strong> ( <i class='arg'>filename</i>) result ( nativename )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>( t_vstring ) ::</strong> <i class='arg'>nativename</i><dd>
</dl>
Returns the platform-specific name of the file. 
filename is useful if the filename is needed to pass to a platform-specific
call, such as the execution of a system command under Windows or
AppleScript on the Macintosh.


<br><br>
<dt><a name="55"><strong>vfile_nativename</strong> ( <i class='arg'>filename</i>) result ( nativename )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>( t_vstring ) ::</strong> <i class='arg'>nativename</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.


<br><br>
<dt><a name="56"><strong>vfile_mkdir</strong> ( <i class='arg'>filename</i> ?, status?)</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Create a directory.
If <i class='arg'>status</i> is supplied, it contains 0 on success or nonzero error code
upon return.
If <i class='arg'>status</i> is not provided and the process could not be done,
an error is generated.


<br><br>
<dt><a name="57"><strong>vfile_mkdir</strong> ( <i class='arg'>filename</i> ?, status?)</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>status</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.




<br><br>
<dt><a name="58"><strong>vfile_open</strong> ( <i class='arg'>filename</i> ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )</a><dd>

<dl>
<dt><strong>type ( t_vstring ), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>fileunit</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>action</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>access</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>form</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>blank</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>position</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>delim</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>pad</i><dd>
<dt><strong>integer , intent(in) , optional ::</strong> <i class='arg'>recl</i><dd>
<dt><strong>integer , intent(out) , optional ::</strong> <i class='arg'>iostat</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>fileunit_real</i><dd>
</dl>
Open a file and returns the unit associated with the opened file.
The command is based on fortran intrinsic &quot;open&quot;.
If the optional argument fileunit is provided, it is used to
open the file.
If not provided, a file unit is automatically computed
on the base of currently free logical units.
<br><br>
Note: 
<br><br>
All the options of the intrinsic &quot;open&quot; are provided
with the same behaviour and default values, with some exceptions.
<br><br>
<ul>
<li> The file name is mandatory in vfile_open,
even if the &quot;file=&quot; specifier is not mandatory in fortran &quot;open&quot;.
This behaviour allows the fortran to manage a status=&quot;scratch&quot;
specifier, which provides a way to manage for temporary
files internally. Instead, the m_vfile component provides the
vfile_tempfile service.
<br><br>
<li> The &quot;err=&quot; option with an error label as argument is not
provided. The client code may use the iostat option instead.
</ul>




<dt><a name="59"><strong>vfile_open</strong> ( <i class='arg'>filename</i> ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )</a><dd>

<dl>
<dt><strong>character(len=*), intent(in) ::</strong> <i class='arg'>filename</i><dd>
<dt><strong>integer, intent(out) , optional ::</strong> <i class='arg'>fileunit</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>action</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>status</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>access</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>form</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>blank</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>position</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>delim</i><dd>
<dt><strong>character(len=*) , intent(in) , optional ::</strong> <i class='arg'>pad</i><dd>
<dt><strong>integer , intent(in) , optional ::</strong> <i class='arg'>recl</i><dd>
<dt><strong>integer , intent(out) , optional ::</strong> <i class='arg'>iostat</i><dd>
<dt><strong>integer ::</strong> <i class='arg'>fileunit_real</i><dd>
</dl>
Same as previous but with <i class='arg'>filename</i> as a character string.

</dl>

<h2><a name="static_methods">STATIC METHODS</a></h2>
<p>

<dl>


<dt><a name="60"><strong>vfile_startup</strong> ()</a><dd>

Initialize module internal state.
This routine must be called once before calling any method of the module.

<br><br>
<dt><a name="61"><strong>vfile_shutdown</strong> ()</a><dd>

Shutdown module internal state.


<br><br>
<dt><a name="62"><strong>vfile_set_stoponerror</strong> ( <i class='arg'>stoponerror</i> )</a><dd>

<dl>
<dt><strong>logical , intent(in) ::</strong> <i class='arg'>stoponerror</i><dd>
</dl>
Configure the behaviour of the component whenever an
error is met.
If <i class='arg'>stoponerror</i> is true, then the execution stops if an error is encountered.
If <i class='arg'>stoponerror</i> is false, then the execution continues if an error is encountered.
In both cases, a message is displayed on standard output.

<br><br>
<dt><a name="63"><strong>vfile_tempdir</strong> () result ( tempdir )</a><dd>

<dl>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>tempdir</i><dd>
</dl>
Returns the temporary directory for the current platform.
The command returns the path of a directory where the caller can
place temporary files, such as &quot;/tmp&quot; on Unix systems.
The algorithm we use to find the correct directory is as follows:
<br><br>
<ol>
<li> The directory named in the TMPDIR environment variable.
<br><br>
<li> The directory named in the TEMP environment variable.
<br><br>
<li> The directory named in the TMP environment variable.
<br><br>
<li> A platform specific location:
    <br><br>
<ul>
    <li> Windows
    &quot;C:\TEMP&quot;, &quot;C:\TMP&quot;, &quot;\TEMP&quot;, and &quot;\TMP&quot; are tried in that order.
    (classic) Macintosh
    The TRASH_FOLDER environment variable is used. filename is most likely not correct.
    <br><br>
<li> Unix
    The directories &quot;/tmp&quot;, &quot;/var/tmp&quot;, and &quot;/usr/tmp&quot; are tried in that order.
    </ul>
</ol>



<dt><a name="64"><strong>vfile_tempfile</strong> result ( tempfile )</a><dd>

<dl>
<dt><strong>type ( t_vstring ) ::</strong> <i class='arg'>tempfile</i><dd>
</dl>
Returns the name of a temporary file name suitable for writing to. 
The <i class='arg'>tempfile</i> name is unique, and the file will be writable and
contained in the appropriate system specific temp directory.


<br><br>
<dt><a name="65"><strong>vfile_volumes</strong> result ( listofvolumes )</a><dd>

<dl>
<dt><strong>type ( t_vstringlist ) ::</strong> <i class='arg'>listofvolumes</i><dd>
</dl>
Returns the absolute paths to the volumes mounted on the 
system, as a proper string list.
On UNIX, the command will always return &quot;/&quot;, since all filesystems are
locally mounted.
On Windows, it will return a list of the available
local drives (e.g. {a:/ c:/}).
<br><br>
Note:
<br><br>
With Intel Fortran, the portability routines provide the &quot;GETDRIVESQQ&quot; function,
which returns the list of current drive as a 26 letters string.


</dl>


<h2><a name="copyright">COPYRIGHT</a></h2>
<p>
Copyright &copy; 2008 Michael Baudin michael.baudin@gmail.com<br>
Copyright &copy; 2008 Arjen Markus arjenmarkus@sourceforge.net<br>
</body></html>